As I've thought on this more, I'm having some concerns about having "single key" magic keys.. unlike QMK, we are far more likely to have someone tapping a key to wake the device and run this early code, potentially with them tapping/accidentally tapping the 0th key to do so.

If we keep this as is, I fear we'll get a lot of accidental triggers. What do folks think about having multiple positions assignable to a given boot magic key? Doesn't need to have fancy combo handling, just enough to track "are all positions pressed that are part of this boot magic key?"

If we keep this as is, I fear we'll get a lot of accidental triggers. What do folks think about having multiple positions assignable to a given boot magic key? Doesn't need to have fancy combo handling, just enough to track "are all positions pressed that are part of this boot magic key?"

That's a valid concern but since we aren't enabling this by default, the users should be aware of the specific key position (or the keyboard designers should tell the users), right? I think it's good to have, rather than must.

What would the effective combo term be? Is it a simple trigger where you want both keys pressed at the time of the check (so the effective term is the boot time) or do we implement logic to wait for keys?

If we keep this as is, I fear we'll get a lot of accidental triggers. What do folks think about having multiple positions assignable to a given boot magic key? Doesn't need to have fancy combo handling, just enough to track "are all positions pressed that are part of this boot magic key?"

That's a valid concern but since we aren't enabling this by default, the users should be aware of the specific key position (or the keyboard designers should tell the users), right? I think it's good to have, rather than must.

Still might have something bump the corner of your keeb and wake it and since the check is just "is this key pressed before the timeout" you'd suddenly potentially lose all your studio customization, etc.

I think this functionality is super useful, but we also shoukd try to design this in a way that's "easy not to screw up".

I also don't trust designers/vendors to consistently communicate this, nor users to always read what is communicated by their vendor.

What would the effective combo term be? Is it a simple trigger where you want both keys pressed at the time of the check (so the effective term is the boot time) or do we implement logic to wait for keys?

I think just "are all keys held at once before the boot magic timeout"

I wonder if "check on boot" is even the right thing to aim for, for wireless devices. I think a "check on usb insertion" might make more sense for those kind of devices. We would lose more function for any keyboards wanting to run hardware without usb support, but those sorts of devices need to be flashed with a programmer and are unlikely to have a bootloader/are more heavy enthusiast.

I wonder if "check on boot" is even the right thing to aim for, for wireless devices. I think a "check on usb insertion" might make more sense for those kind of devices. We would lose more function for any keyboards wanting to run hardware without usb support, but those sorts of devices need to be flashed with a programmer and are unlikely to have a bootloader/are more heavy enthusiast.

I like where you're thinking! Why don't we use the hwinfo API to determine the reset reason, and ignore the boot magic unless it's one of the "valid" reasons (.e.g. reset pin or power-on-reset)? I think that might a good way to avoid the accidental triggers from a key press to wake, and allow simple one button boot magic.

Adding support for combos probably wouldn't be too hard either. You could add a bool[] of the same size as the key positions array (or bitfield, though that wouldn't really save space unless you do something silly like a 5+ key combo) to the driver data to store the pressed states of each of the key positions. Track both presses and releases until the timeout expires, and if every element of the array is true after a key event, trigger the boot magic logic.

Adding support for combos probably wouldn't be too hard either. You could add a bool[] of the same size as the key positions array (or bitfield, though that wouldn't really save space unless you do something silly like a 5+ key combo) to the driver data to store the pressed states of each of the key positions. Track both presses and releases until the timeout expires, and if every element of the array is true after a key event, trigger the boot magic logic.

Yeah, my thoughts exactly. We don't need crazy "combo" logic here.

I think it would be a good idea to predefine a bootloader boot magic key for our in-tree keyboards. Maybe top left key as a convention, mirrored for splits?

I could use some more clarity on how to handle physical layouts here. Should the bootmagic key/combo be defined independently for each physical layout? Or defined in terms of the kscan row and column? Or keep the behavior as-is?

@rianadon I suspect you're not asking about the problem I filled as #3228 (not specific to the bootloader actions at startup), but the equivalent ambiguity for the low level combos being discussed here (with BOOT_KEY_COMBO_POSITIONS specific to startup).

@rianadon I suspect you're not asking about the problem I filled as #3228 (not specific to the bootloader actions at startup), but the equivalent ambiguity for the low level combos being discussed here (with BOOT_KEY_COMBO_POSITIONS specific to startup).

I was referring to the issues @joelspadin and @caksoylar brought up in their discussion above, but your problem does sound relevant. Even though we are working at different layers, the user-facing configuration for combos and bootmagic should ideally be very similar.

I've revised the configuration of the boot magic combos to happen at the physical layout layer instead of the global layer as @caksoylar has suggested. I think overall this is the cleanest approach, and it also makes working with split keyboards nicer.

Here's how the example in the docs for boot magic key configuration on a split keyboard with two physical layouts looks:

shield.dtsi

/ {
    chosen {
        zmk,physical-layout = &default_layout;
    };

    default_layout: default_layout {
        compatible = "zmk,physical-layout";
        display-name = "Default Layout";
        transform = <&default_transform>;
    };

    five_column_layout: five_column_layout {
        compatible = "zmk,physical-layout";
        display-name = "5-Column Layout";
        transform = <&five_column_transform>;
    };

    bootloader_key_left: bootloader_key_left {
        compatible = "zmk,boot-magic-combo";
        combo-positions = <0>;
        jump-to-bootloader;
    };

    bootloader_key_right: bootloader_key_right {
        compatible = "zmk,boot-magic-combo";
        combo-positions = <11>;
        jump-to-bootloader;
    };

    bootloader_key_right_fivecol: bootloader_key_right_fivecol {
        compatible = "zmk,boot-magic-combo";
        combo-positions = <9>;
        jump-to-bootloader;
    };
    ...
};

shield_left.overlay

#include "shield.dtsi"

&default_layout {
    boot-magic-combos = <&bootloader_key_left>;
};
&five_column_layout {
    boot-magic-combos = <&bootloader_key_left>;
}

shield_right.overlay

#include "shield.dtsi"

&default_layout {
    boot-magic-combos = <&bootloader_key_right>;
};
&five_column_layout {
    boot-magic-combos = <&bootloader_key_right_fivecol>;
}

shield.keymap

// Uncomment this block if using the 5-column layout
// / {
//     chosen {
//         zmk,physical-layout = &five_column_layout;
//     };
// };